Amiga Collections: MegaDisc/MegaDisc 32 (1993-02)(MegaDisc Digital Publishing)(AU)(Disk 2 of 2).zip/MegaDisc 32 (1993-02)(MegaDisc Digital Publishing)(AU)(Disk 2 of 2).adf/hyperbook/HB_Macros

Text File | 1993-02-11 | 17KB | 351 lines

                     M a c r o s   i n
                                                   by John Collett
                     H y p e r B o o k



     Do it in RAM:

    This package is in three parts :

      (a) The HyperBook 'HBReader' program.
      (b) A hyperbook unit called 'defaulthyperbook'. When you click on
          the 'HBReader' icon, this unit is automatically selected.
      (c) This article, 'HB_Macros', for which it is assumed that FullView
          is available.

    They should all be in the same directory.  If, for a really smooth
    performance, you decide to run this presentation in Ram:, then move
    the whole of the current drawer, as it stands.

     Purposes of this presentation

    1  To acknowledge the quality of HyperBook.

    2  To show off, briefly, a few of its main features, for readers who
    haven't yet seen it in action.

    3  To mention the remarkable HyperBook Macro Language (HML) which comes
    as an added bonus with HyperBook.

    4  To go a little deeper into the topic of ARexx macros in Hyperbook,
    and to provide examples of the kind of thing they can do.

    5  To explain how the article itself serves as raw material for some
    of the macros we shall be discussing.

    6  To show how another program can be run from within HyperBook.
    FullView could be used to display this text, and access to it could
    be via the HyperBook unit.


     Introduction

    Except at startup, I rarely see my WorkBench or a CLI window nowadays.
    No, I haven't got DirOpus; I have HyperBook, which sets up a tailor-
    made working environment for me. Everything I need is readily
    available, and that environment is easy to modify.

    It is often the case with commercial packages that once you are using
    them you are in a straight-jacket designed by the authors, and you keep
    saying "If only it would let me do this!" or "Why can't I do that?" I
    haven't had that feeling with HyperBook, in which I find I can do most
    of the things I ever wanted to do or tried to do in a traditional
    programming language, and can do many of them more easily.

    There has been and still is some learning to be done, of course, but
    the manual is well-written and the disks are full of examples.
    Literally within minutes you can have your first own hyperbook up and
    running. You can easily cross the magic threshold into ARexx (assuming
    you have it), and then you can start to explore the excellent built-in
    HyperBook Macro Language. Before long you will have unlocked the
    treasure chest of macros, exploring the examples supplied, and moving
    into the more challenging area of writing and using your own.

    Perhaps the clearest way I can express my satisfaction with HyperBook
    is to say that I have both AmigaVision and CanDo, but don't use either
    of them.

     HyperBook Macro Language

    From the manual:

     ---------------------------------------------------------------------
    |        HyperBook         "a general purpose multi-media tool that   |
    |        (page 1)           lets you store and organize text and      |
    |                           graphics in any format."                  |
    |                                                                     |
    |    HyperBook + ARexx     "to offer you additional capabilities."    |
    |       (page 109)                                                    |
    |                                                                     |
    | HyperBook + ARexx + HML  "let's you create 'intelligent'            |
    |       (page 109)          applications of almost                    |
    |                           unlimited flexibility."                   |
     ---------------------------------------------------------------------

    HML is a collection of 130 or so ready-made macros, an extremely useful
    addition to your programming tools, facilitating work in various areas
    under the following headings:

      HyperBook control   |  Page editing         |   Searches
      Navigation          |  Object creation      |   User input
      Main control panel  |  Object editing       |   Text editing
      General editing     |  Actions              |   Printing
      Page creation       |  Note and button text |   Data display
      Master pages        |  Items and lists      |   Language support
      Page files          |                       |

    The HyperBook Samples disk contains a large hyperbook tutorial
    called ARexx.hb which demonstrates and explains all the HML functions.
    The disk also contains various other HyperBook goodies such as an
    AddressBook, AppointmentsBook, Calendar and Calculator.

    It was immediately obvious that the best way to learn how all the
    functions behave was to use them.  So I wrote my own sequence of
    'pages', systematically using practically every one of the 130
    functions, from 'num = NUMPAGES()' (manual page 117) to 'value =
    RAND(low, high) on page 131.  When I got stuck (one or two misprints in
    the manual, or I was having a bad day), I consulted ARexx.hb to see how
    the masters had done it, and all was well. The authors do in fact
    advise that procedure, and acknowledge that the manual is less accurate
    than the tutorial program.

    Then it was time to use what I had learned in something more
    challenging.

     The Macro Samples on the Samples Disk

      Samples: macros
        Bevel{obj}                       CenterObject
        ExecuteText                      FileToList{fname}
        FileToNote{fname}                GetObjSize
        ListCurrentPage                  SaveListText{list,fname}
        SaveNoteText{note,fname}         SavePageColors
        SetItemActions                   SetObjSize
        StdColorSet
         sample (dir)
          ActionInfo                       ChangeNoteNames
          CloneItem                        CloneThisPage
          TextRange{fname,first,nlines}

    The five macros in the separate 'sample' directory, are described (p.140)
    as 'some less general examples'.

    Braces, {} not (), are used to indicate the type and number of
    arguments which need to be passed when some of these macros are called,
    braces being needed to make the entries legal in the above list.  But
    when they are used, then the standard form of brackets are required.
    In fact the macro editor makes the change for you.

    Exploring these macros was easy, but my insights needed sharpening, and
    my memory needed a prop.  In the process, I used one or two of the
    provided macros as well as constructing some of my own :

    1 To obtain the above directory listing from the Samples disk and
      convert it into a HyperBook 'List'.

    2 To set 'actions' for each member of that list, so that a click on
      any of them would :

       (a) Obtain the few lines of explanatory comment from the
           head of the relevant file.
       (b) Convert that piece of text into a HyperBook 'Note',
           and tidy up its format.
       (c) Position and size the note according to the length
           of text it was to contain.

    This all worked astonishingly well, and I decided to share the pleasure
    with my one or two regular MegaDisc readers.  The reduced form of
    HyperBook, the 'HBReader', would be fine for the presentation, but other
    logistic matters were less easy to solve.  It would be out of the
    question to include all the macros just to demonstrate how a part of
    each one could be extracted and presented as a note. So I decided
    instead to use the text of this article as source material for similar
    if not identical macro demos.

    Introductory Demos
                                                      Its macro
          #1  Sample 'objects' and 'actions'          ListJobs
          #2  A look-alike of the full HB menu        ShowMenu

    Demos using the Article

          #3  Information on the article              FileInfo
          #4a Making a list of subheadings            SubHeadings
            b Setting a 'readpatch' action
          #5  Converting tables to 'Lists'            Table
          #6  Building a 'Note'                       SecretMessage

     Introductory Demos

      #1 Sample 'objects' and 'actions'

    If you've got ARexx, explore all the objects you see on the first demo
    'page' by clicking on them. Except for the List, their actions have
    been set by ARexx commands.  In the List, click on each of its items.
    Their actions are dealt with by a single macro I've called ListJobs,
    which makes use of the following HML functions:

          Initiator()      GetLeft()        ShadowStyle()
          Inform()         GetTop()         SetBorder()
          GetName()        SetPosition()    SetShadow()
          ReadNoteText()   GetWidth()       ShadowStyle()
          DeleteText()     GetHeight()      GetItemText()
          InsertText()     Scale()          SetItemText()


      #2 A look-alike of the full HB menu

    It's a reasonable imitation of the real thing, though of course none of
    the items work, and it shows none of the sub-menus.  When each menu
    header is clicked, a small macro toggles 'off' any other menu list
    which may have just been looked at.

     Demos using the Article

      #3 Information on the article

       To confirm that the article exists, and provide related information.

    Main steps in macro :

    1 Is 'rexxsupport.library' active?  If not, use 'addlib()'.
    2 Successful?
      (a) If so, then :
            Call 'statef()' and parse the result
            Assemble 'text' as required
            Set position and size variables for new 'Note'
      (b) If not, use DOS instead of ARexx :
            address command 'list >ram:temp article_file_name'
            Load 'ram:temp' into 'text'.
            Set position and size
    3 Create a new 'Note', insert the text, scale it to size, set it
      in position, set its name, and relocate it from the 'bin' where
      it is created to the required page - all done by HML commands
      carrying the appropriate arguments.


      #4a A list of subheadings

       To extract and build into a 'List' all the article subheadings.

    In fact demos #4a and #4b use the same macro, but its work will be
    described in two stages.

    Main steps in macro :

    1 Use a DOS search command ('address command etc.') to find all lines
      in the source file which carry the colour coding for a subheading.
      Store the output in a temporary file.
    2 Create a new 'List', small, empty, in the 'bin'.
    3 Open the temporary file, read in each line, strip off the colour
      codings, and append each line as an 'item' in the 'list'.
    4 At eof, leave the loop, close the file, and delete it.
    5 Scale the list to size, set it in position, set its name, and
      relocate it.

    (On reflection, that temporary file is probably not necessary - instead,
    put item 2 first, then find, strip, and append each subheading - but it
    seemed like a good idea at the time.)

    The list of subheadings is then in place. How to make use of it is
    described under Demo #4b.

      #4b Setting a 'readpatch' action

       To set an 'action' for each item in the Demo #4a list, to
       display the patch of text which comes under the particular
       subheading.

    The patches are too long to be 'Notes', and so HyperBook's text reader
    is used to present them.  HyperBook contains its own text editor and
    text reader.  Both of them are surprisingly good for such features
    included as part of a larger package, and both pleasant to handle. The
    reader handles ANSI colours in a slightly different way from FullView,
    and such codings in this article are not quite the same as I usually
    use for a MegaDisc article, so that the text will appear in reasonable
    shape either via FullView or via the HB text reader.

    While I have tried to keep all these demo macros as 'dynamic' as
    possible, that is, have them do their complete job when they are
    called, I decided to cheat a bit on this one, to avoid having to
    include a sizeable HyperBook utility called 'TextRange'.

    When the HML function 'ShowTextRange' is called to screen a patch of a
    file, it needs to know how many bytes into the file the required patch
    starts, and how many bytes are to be screened. This sort of information
    is not immediately available, but can be obtained by supplying the
    TextRange utility with the number of the first line and the number of
    lines to be included - information which is easy to obtain.  I have
    used TextRange in advance, and the values required for ShowTextRange
    are stored in an invisible list called 'Bytes' on the page concerned.

    Main steps in macro :

    1 Confirm object numbers for lists called 'Bytes' and 'SubHeadings'
      using SearchName().

    2 Loop through all the elements in the 'Subheadings' list :

    (a) Obtain the 'start' and 'amount' values from the corresponding
        entry in 'Bytes'.
    (b) Set the 'action' for the 'Subheadings' item to 'ShowTextRange',
        with the 'start' and 'amount' just obtained.

      #5 Converting tables to 'Lists'

      To extract a table from the article, and format it into a 'List',
      but with no further 'actions', since I have to stop somewhere.

    One example is enough for this demonstration and I decided to use the
    table of HML topics which you may have seen about six screens ago. I do
    not want just to screen the text as was done in Demo #4b, so
    ShowTextRange is not needed. Instead, I use ARexx 'seek' to find the
    starting point in the article, and then the 'readln()' function to read
    in the few lines needed.

    Like ShowTextRange, 'seek' needs to know the number of bytes, and so
    once again I used the ShowRange utility, in advance, to obtain that
    value.

    Main steps in macro :

    1  Open the source file.
    2  Go to the required point using 'seek'.
    3  Create a new and empty 'List'.
    3  Read in lines from the source table until an empty line is reached.
    4  Divide each line at '|' to create a single column.
    5  Append each part-line as an 'item' in the 'list'.
    6  Scale the list to size, set it in position, set its name, and
       relocate it.


      #6 Building a 'Note'

    There is an invisible message here (text in the background colour!).
    Demo #6 will find it and display it in a 'Note', using steps similar to
    those in Demo #5.  Colours, frame, font, style, text spacing, line
    spacing, formatting, etc. are all handled automatically in the process.

   .I hereby acknowledge with respect and
   .gratitude the superb work done by
   .Chris Zamara and Nick Sullivan,
   .the authors not only of HyperBook,
   .but also of 'Using ARexx on the Amiga'.
   .
   .     Great stuff, you guys!

    This is the only source of the text of the message which you will see.
    It could have been hidden in a ready-made but invisible 'Note', made
    visible when you ask to see it, but that would not have shown the
    process of constructing a note from separate source material.


     Hamilton, NZ, November, 1992

                =========================================